home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / program / asm32.zip / INPUT.DOC < prev    next >
Text File  |  1996-01-21  |  33KB  |  1,064 lines
  1.  
  2. ********************************  INPUT  ************************************
  3.  
  4. ASM32 Input subroutines (C) Copyright 1993 - 1995 Douglas Herr
  5. all rights reserved
  6.  
  7. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  8.  
  9. $EDIT:       editor module used by TEdit and GEdit.
  10.              Must be called by GEdit or TEdit
  11. Source:      $edit.asm (getkey.asm, isdigit.asm, toupper.asm, tolower.asm)
  12.  
  13.              TEdit and GEdit edit a string on a single row of the screen
  14.              (without word wrap).  Strings longer than the column width of
  15.              the screen are scrolled left or right as required.  A public
  16.              byte in $edit's data area, EWIDTH, establishes the effective
  17.              screen width limit.  EWIDTH is a not-to-exceed limit; if the
  18.              actual screen width is less than EWIDTH, EWIDTH is ignored
  19.              and the actual screen width is used instead.  ASM32's default
  20.              EWIDTH is 132.
  21.  
  22.              $edit commands for both TEdit and GEdit are:
  23.  
  24.              Ctrl+left arrow = word left
  25.              Ctrl+right arrow = word right
  26.              Ctrl+end = clear to end of string
  27.              Home = go to start of string
  28.              End = go to end of string
  29.  
  30.  
  31.              Option bits, passed to GEdit or TEdit in register AL, are:
  32.  
  33.              Option 1 = upper case input
  34.              Option 2 = lower case input
  35.              Option 1 OR 2 = digits only input
  36.  
  37.  
  38. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  39.  
  40. CLEARKEY:    clears the keyboard's 'type-ahead' buffer
  41.              Uses BIOS functions to remove all keys in the buffer.
  42. Source:      clearkey.asm (keywait.asm, getkey.asm, kbdtype.asm)
  43.  
  44. Call with:   no parameters
  45. Returns:     nothing
  46. Uses:        nothing
  47. Example:
  48.  
  49. extrn   clearkey:near
  50.  
  51. include codeseg.inc
  52.  
  53.         .
  54.         .
  55.         .
  56.         call   clearkey
  57.  
  58.  
  59.  
  60. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  61.  
  62. GEDIT:       string editor for graphics modes
  63.              See also TEdit for text modes, $EDIT for general information
  64. Source:      gedit.asm ($edit.asm, gprint.asm, $graph.asm, gcursor.asm,
  65.                         gputchr.asm)
  66.  
  67. Call with:   ESI pointing to string buffer; may include a default string
  68.              EDX pointing to x- & y-coordinates
  69.              ECX = byte size of buffer
  70.              AL = option bits (see $edit)
  71.              GEdit only works with DrawMode 1 or -1 (see DrawMode in
  72.              GRAPHICS.DOC).  GEdit forces drawmode to 1 or -1 and restores
  73.              the previous drawmode on exit.
  74. Returns:     AX = last key pressed (see getkey for key codes)
  75.              ECX = new string length
  76. Uses:        EAX, ECX, flags
  77. Supports:    all ASM32 graphics modes
  78. Example:
  79.  
  80. include dataseg.inc
  81.  
  82. ; data
  83. x       dw 8                      ; x-coordinate (pixels from left edge)
  84. y       dw 100                    ; y-coordinate (pixels from top of screen)
  85. extrn   ewidth:byte               ; byte in $edit used to limit columns
  86.                                   ; displayed
  87. @curseg ends
  88.  
  89. include codeseg.inc
  90.  
  91.         .
  92.         .
  93.         .
  94.         mov   ewidth,40           ; there's stuff on the right side of
  95.                                   ; the screen that should be left alone
  96.  
  97.         lea   esi,string_buffer   ; near address of string buffer
  98.         mov   ecx,len_buffer      ; byte length of buffer for the string
  99.         mov   al,0                ; nothing tricky
  100.         lea   edx,x               ; point to x & y coordinates
  101.                                   ; see GPrint for explanation of x and y
  102.         call  gedit
  103.  
  104.  
  105.  
  106. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  107.  
  108. GETKEY:      returns next key pressed
  109. Source:      getkey.asm (kbdtype.asm)
  110.  
  111. Call with:   no parameters
  112. Returns:     AL = ASCII key code
  113.              AH = 0 if normal key
  114.              AH = 1 if extended key code (such as function keys)
  115. Uses:        AX
  116.              Uses BIOS functions; supports enhanced keyboard if present
  117. Supports:    standard and enhanced keyboards
  118. Example:
  119.  
  120. extrn   getkey:near
  121.  
  122. include codeseg.inc
  123.  
  124.         .
  125.         .
  126.         .
  127.         call  getkey
  128.         shr   ah,1            ; a function key?
  129.         jc    function_key    ; jump if so
  130.  
  131.  
  132. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  133.  
  134. GETMARKED:   returns pointer to string marked by MarkFile
  135. Source:      getmarkd.asm (strlen.asm)
  136.  
  137. Call with:   EDI = near address of filename list marked by MarkFile
  138.              EAX = filename index number (first marked file index = 0)
  139. Returns:     if EAX = valid marked file index, [EBX] points to full filename
  140.                                                 ECX = length of filename
  141.              If GetMarked is called with EAX = -1, the filename at the
  142.              MarkFile cursor is returned at [EBX] whether it was marked
  143.              or not.
  144.              If EAX too big, CF = 1
  145. Uses:        EBX, ECX, flags
  146. Example:     see MARKFILE
  147.  
  148.  
  149. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  150.  
  151. ISALPHA:     determines if a keycode returned by GetKey is a letter from
  152.              A-Z or a-z.
  153. Source:      isalpha.asm
  154.  
  155. Call with:   AX = keycode returned by GetKey.
  156. Returns:     if CF = 0, keycode is a character from A-Z or a-z
  157.              if CF = 1, keycode is not a character from A-Z or a-z
  158.              AX is not changed
  159. Uses:        CF
  160. Example:     call   getkey       ; get next keystroke
  161.              call   isalpha
  162.              jc     not_alpha
  163.  
  164.  
  165. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  166.  
  167. ISDIGIT:     determines if a keycode returned by GetKey is the ASCII code
  168.              for the numeric characters 0-9
  169. Source:      isdigit.asm
  170.  
  171. Call with:   AX = keycode returned by GetKey.
  172. Returns:     if CF = 0, keycode is a character from 0-9
  173.              if CF = 1, keycode is not a character from 0-9
  174.              AX is not changed
  175. Uses:        CF
  176. Example:     call   getkey       ; get next keystroke
  177.              call   isdigit      ; I want numbers only
  178.              jc     not_a_number
  179.  
  180.  
  181.  
  182. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  183.  
  184. ISLOWER:     determine if a keycode returned by GetKey is lower case
  185. Source:      islower.asm
  186.  
  187. ISUPPER:     determine if a keycode returned by GetKey is upper case
  188. Source:      isupper.asm
  189.  
  190. Call with:   AX = keycode returned by GetKey.
  191. Returns:     if CF = 0, keycode is a character from A-Z or a-z
  192.              if CF = 1, keycode is not a character from A-Z or a-z
  193.              AX is not changed
  194. Uses:        CF
  195. Example:     call   getkey       ; get next keystroke
  196.              call   isupper      ; is it upper case?
  197.              jc     not_upper    ; no; could be lower case
  198.  
  199.  
  200.  
  201. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  202.  
  203. JANEIN:      German language version of YesNo
  204.              waits for 'J' or 'N' key to be pressed
  205. Source:      janein.asm
  206.  
  207. Call with:   no parameters
  208.              Key pressed may be upper or lower case.  Upper case is
  209.              returned.  Uses BIOS functions
  210. Returns:     AX = 'J' or AX = 'N'
  211.              future version will also return ^C
  212. Uses:        AX
  213. Example:
  214.  
  215. extrn   JaNein:near
  216.  
  217. include codeseg.inc
  218.  
  219.         .
  220.         .
  221.         .
  222.         call  JaNein
  223.  
  224.  
  225.  
  226. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  227.  
  228. KEYORBUTTON: waits for first keypress or mouse button click
  229. Source:      mouse.asm (getkey.asm, kbdtype.asm)
  230.  
  231. Call with:   no parameters
  232.              If a keypress is waiting in the keyboard buffer before
  233.              this subroutine is called, the keycode is returned to
  234.              the calling program without checking mouse button status.
  235. Returns:     AX = keycode, BX = mouse button code (see MouseStatus)
  236. Uses:        AX, BX
  237. Example:     call   keyorbutton
  238.  
  239.  
  240.  
  241. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  242.  
  243. KEYWAITING:  Determines if a key is waiting in the keyboard buffer.
  244.              Does not remove the key code from the buffer.  Uses BIOS.
  245. Source:      keywait.asm (kbdtype.asm)
  246.  
  247. Call with:   no parameters
  248. Returns:     CF = 1 if no key waiting
  249.              CF = 0 if key waiting
  250. Uses:        CF
  251. Example:
  252.  
  253. extrn   keywaiting:near
  254.  
  255. include codeseg.inc
  256.  
  257.         .
  258.         .
  259.         .
  260.         call   keywaiting
  261.         jc     no_key_pressed
  262.         call   getkey           ; get the key that was pressed
  263.  
  264.  
  265.  
  266. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  267.  
  268. MARKCOUNT:   determines number of filenames marked in valid MarkFile list
  269. Source:      markcnt.asm
  270.  
  271. Call with:   EDI = address of filename list returned by MarkFile
  272. Returns:     EAX = number of filenames marked
  273. Uses:        EAX, flags
  274. See also:    MARKFILE, GETMARKED
  275. Example:     see MARKFILE, next page
  276.  
  277.  
  278. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  279.  
  280. MARKFILE:    display a list of filenames, marking one or more for later
  281. Source:      markfile.asm ($menu.asm, getkey.asm)
  282.  
  283. Call with:   ESI = near pointer to filespec
  284.              CX = file attributes
  285.  
  286.              [text modes]
  287.              EAX = near offset of ASM32's $TPICK module
  288.              DH = screen row for top of list
  289.              DL = screen column for left side of list
  290.  
  291.              [graphics modes]
  292.              EAX = near offset of ASM32's $GPICK module
  293.              EDX = near pointer to (x,y) graph coodinates for top of list
  294.  
  295.  
  296.              If CX bit 4 (directory attribute) is set, ALL subdirectories
  297.              of the specifed path are displayed, whether they match the
  298.              filespec or not.
  299.  
  300.              Files may be marked with the '+' key, unmarked with '-';
  301.              Esc or Enter returns control to the calling program.  Use
  302.              the Up, Down, PageUp, PageDown, Home and End keys to move
  303.              the cursor.
  304.  
  305.              If MarkFile is called with ESI pointing to a NUL byte,
  306.              it assumes that EDI is the address of a filename list
  307.              previously created by MarkFile and displays the list again.
  308.  
  309. Returns:     If CF = 0:
  310.               EDI = address of filename structure
  311.               AX = keycode pressed to exit MarkFile
  312.               If the '+' key was pressed with the cursor positioned at
  313.               the name of a directory, AX = '+'.
  314.  
  315.              If CF = 1, AX = DOS error code
  316.  
  317. Uses:       AX, EDI, CF
  318. Supports:   All ASM32 text and graphics modes; MENUOPTION colors
  319.             [text modes] MENUOPTION frame styles
  320.  
  321. See also:   MARKCOUNT, GETMARKED, MENUOPTION
  322.  
  323. Example on next page
  324.  
  325.  
  326. ; MarkFile example, using conditional assembly directives to illustrate
  327. ; use of MarkFile with either Text mode of Graphics mode screen:
  328.  
  329. include model.inc
  330.  
  331. extrn   markfile:near, markcount:near, getmarked:near
  332. IFDEF   GRAPHMODE
  333. extrn   $gpick:near
  334. ELSE
  335. extrn   $tpick:near
  336. ENDIF
  337.  
  338. include dataseg.inc
  339. files   db '*.asm',0        ; look for all .ASM files in current directory
  340. IFDEF   GRAPHMODE
  341. xy      dw 10,10
  342. ENDIF
  343. @curseg ends
  344.  
  345. include codeseg.inc
  346.          .
  347.          .
  348.          .
  349.         lea     esi,files
  350.         mov     cx,10h         ; normal files + directories
  351.  
  352. IFDEF   GRAPHMODE
  353. ; any ASM32 graphics mode
  354.         mov     eax,offset @curseg:$gpick
  355.         lea     edx,xy
  356. ELSE
  357. ; any ASM32 text mode
  358.         mov     eax,offset @curseg:$tpick
  359.         mov     dx,0303h       ; 4th row, 4th column
  360. ENDIF
  361.         call    markfile
  362.         jc      short done
  363.  
  364. ; were any marked?
  365.         call    markcount
  366.         test    ax,ax          ; any marked?
  367.         jnz     several_marked
  368.         dec     eax            ; get filename at cursor
  369.         jmp     short filename_loop
  370.  
  371. several_marked:
  372.         xor     eax,eax
  373. filename_loop:
  374.         call    getmarked
  375.         jc      short done
  376.         call    do_something_with_the_file
  377.         inc     eax
  378.         jmp     filename_loop
  379.  
  380. done:
  381.  
  382.  
  383. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  384.  
  385. MASKEDIT:    edit one or more fields with a non-editable mask
  386. Source:      maskedit.asm (getkey.asm, tprint.asm, strlen.asm, cursor.asm)
  387.  
  388. Call with:   ESI pointing to mask string
  389.              DH = screen row
  390.              DL = screen column
  391.              AH = color attribute
  392.              AL = option bits
  393.                   00b = all alphanumeric characters
  394.                   01b = convert input to lower case
  395.                   10b = convert input to upper case
  396.                   11b = numeric input only
  397.  
  398.              MaskEdit allows only alphanumeric and space characters in the
  399.              string to be changed.  All other characters are protected from
  400.              changes and are skipped by the cursor.
  401.  
  402. Returns:     AX = Esc or Enter ASCII code
  403. Uses:        EAX
  404. Example:
  405.  
  406. ; I want to prompt for a telephone number
  407. ; note that ASCII 255 may be used as a non-editable space character
  408.  
  409. extrn   maskedit:near
  410.  
  411. include dataseg.inc
  412.  
  413. extrn   row:byte, column:byte, color:byte
  414.  
  415. phonenumber     db 'Telephone:',255,'(916)',255,'721-8762',0
  416.  
  417. @curseg ends
  418.  
  419. include codeseg.inc
  420.         .
  421.         .
  422.         .
  423.         mov     dh,row
  424.         mov     dl,column
  425.         mov     al,3             ; numerals only
  426.         mov     ah,color
  427.         lea     esi,phonenumber
  428.         call    maskedit
  429.  
  430.  
  431. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  432.  
  433. MENUOPTION:  options for PULLDOWN, PICKFILE, PICKSTRING
  434. Source:      $menu.asm
  435.  
  436. Call with:   AX = option value
  437.              BX = option number
  438.  
  439.              If you do not specify any options or if you call MenuOption
  440.              with AX = 0, default values are assumed.
  441.  
  442.              options available are:           defaults:
  443.                0 = normal text color            07h
  444.                1 = current selection color      70h
  445.                2 = list box color               0Fh
  446.                3 = hotkey color                 0Fh         (1)
  447.                4 = optional quitkey             no quitkey  (2)
  448.                5 = exit when hotkey pressed     00h         (3)
  449.                6 = box frame type (see WFRAME)  -1          (4)
  450.                7 = procedure address to call
  451.                    before reading key           none        (5)
  452.  
  453. NOTE: DEFAULT COLORS MAY NOT BE SUITABLE FOR SOME GRAPHICS MODES
  454. Colors for text modes should be the same color code used with
  455. text-mode ASM32 subroutines, except that the color code should be
  456. passed to MENUOPTION in register AL, not register AH as in ASM32's
  457. TEXT subroutines.  In Graphics modes, the color should be passed to
  458. MENUOPTION in register AL (foreground) and AH (background) exactly as
  459. though you were calling GCOLOR.
  460.  
  461. (1) the first upper-case letter in each string is that string's hotkey
  462.     no upper-case character = no hotkey
  463. (2) the quitkey value is a keycode returned by GetKey
  464. (3) use AX = -1 for exit when hotkey pressed, AX = 0 to disable
  465. (4) text modes only
  466. (5) calls specified procedure with EBX set as if on exit
  467.  
  468. Returns:     nothing
  469. Uses:        nothing
  470. Supports:    PICKFILE, PULLDOWN, PICKSTRING menu systems
  471. Example:
  472.  
  473. extrn   menuoption:near, pickstring:near
  474.  
  475. include codeseg.inc
  476.  
  477.           .
  478.           .
  479.           .
  480.           mov   bx,0         ; text color
  481.           mov   ax,23        ; white w/ blue background
  482.                              ; 16-color in graph modes, this would be
  483.                              ; MOV  AX,0107h  (see GCOLOR in GRAPHICS.DOC)
  484.           call  menuoption
  485.  
  486.  
  487. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  488.  
  489. MOUSELIMIT:  limits mouse's range of motion
  490. Source:      mouse.asm
  491.  
  492. Call with:   EBX pointing to pixel coordinates of minimum and maximum
  493.              x and y limits.  X-limits are the horizontal dimension and
  494.              y-limits are the vertical dimension.
  495. Returns:     nothing
  496. Uses:        nothing
  497. Example:
  498.  
  499. include dataseg.inc
  500.  
  501. x0    dw 30
  502. y0    dw 15
  503. x1    dw 620
  504. y1    dw 250
  505.  
  506. @curseg ends
  507.  
  508. include codeseg.inc
  509.  
  510.        .
  511.        .
  512.        .
  513.       lea    ebx,x         ; EBX points to limits
  514.       call   mouselimit
  515.  
  516.  
  517.  
  518. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  519.  
  520. MOUSEPOS:    sets the mouse's position
  521. Source:      mouse.asm
  522.  
  523. Call with:   EDX pointing to desired x- and y-coordinates
  524.              Note that mouse coordinates are expressed as a pixel location
  525.              as with graphics mode, even if the system is in text mode
  526. Returns:     nothing
  527. Uses:        nothing
  528. Example:
  529.  
  530. extrn   mousepos:near
  531.  
  532. include dataseg.inc
  533.  
  534. x     dw 100
  535. y     dw 25
  536.  
  537. @curseg ends
  538.  
  539. include codeseg.inc
  540.  
  541.       .
  542.       .
  543.       .
  544.       lea    edx,x         ; EDX points to desired position
  545.       call   mousepos
  546.  
  547.  
  548. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  549.  
  550. MOUSESTATUS: determine mouse position & buttons pressed
  551. Source:      mouse.asm
  552.  
  553. Call with:   no parameters
  554. Returns:     if ZF = 1, no buttons are pressed
  555.              if ZF = 0, BX = button code
  556.               BX bit 0 if set = left button is down
  557.               BX bit 1 if set = right button is down
  558.               BX bit 2 if set = center button is down
  559.              CX = horizontal (x) coordinate
  560.              DX = vertical (y) coordinate
  561.              Note that mouse positions are expressed as a pixel location
  562.              as with graphics mode, even if the system is in text mode
  563. Uses:        EBX, ECX, EDX, flags
  564. Example:     call  mousestatus
  565.              jz    no_buttons     ; no buttons pressed if ZF = 1
  566.  
  567.  
  568.  
  569. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  570.  
  571. OUINON:      French language version of YesNo
  572.              waits for 'O' or 'N' key to be pressed
  573. Source:      ouinon.asm
  574.  
  575. Call with:   no parameters
  576.              Key pressed may be upper or lower case.  Upper case is
  577.              returned.  Uses BIOS functions
  578. Returns:     AX = 'O' or AX = 'N'
  579.              future version will also return ^C
  580. Uses:        AX
  581. Example:
  582.  
  583. extrn   ouinon:near
  584.  
  585. include codeseg.inc
  586.  
  587.         .
  588.         .
  589.         .
  590.         call  OuiNon
  591.  
  592.  
  593.  
  594.  
  595.  
  596. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  597.  
  598. PICKFILE:    pick a file from a list of filenames
  599.              PickFile pops a window on the screen and displays filenames
  600.              matching an input filespec mask.  One filename may be selected
  601.              with cursor keys or with hotkeys.  When Esc or Enter is
  602.              pressed, PickFile restores the screen and returns the selected
  603.              filename to the calling program.
  604.  
  605.              PickFile allocates a block of near memory which should be
  606.              released after you are done with it.  See example;  See also
  607.              MenuOption.
  608. Source:      pickfile.asm (filelist.asm)
  609.  
  610. Call with:   ESI pointing to filespec mask
  611.              BX = initial cursor position
  612.              CX = file attribute mask
  613.  
  614.              [text modes]
  615.              EAX = near pointer to ASM32's $TPICK module
  616.              DH = top screen row for list
  617.              DL = left screen column for list
  618.  
  619.              [graphics modes]
  620.              EAX = near poitner to ASM32's $GPICK module
  621.              EDX = near pointer to (x,y) screen coordinates
  622.                    for upper left corner of filename list
  623.  
  624. Returns:     if CF = 0, EAX = last key pressed
  625.                         EBX points to filename selected
  626.              if CF = 1, no filenames match input filespec
  627. Uses:        EAX, EBX, flags
  628. Supports:    all ASM32 text modes and graphics modes
  629.  
  630. Example on next page
  631.  
  632. ; PICKFILE Example uses conditional assembly directives to illustrate
  633. ; use of PickFile with either Text mode or Graphics mode screen:
  634.  
  635. include model.inc
  636.  
  637. public  myproc
  638. extrn   pickfile:near
  639. IFDEF   GRAPHMODE
  640. extrn   $gpick:near
  641. ELSE
  642. extrn   $tpick:near
  643. ENDIF
  644.  
  645. include dataseg.inc
  646.  
  647. filespec db '*.asm',0            ; search for ASM source code
  648. IFDEF   GRAPHMODE
  649. xy       dw 0,0
  650. ENDIF
  651.  
  652. @curseg ends
  653.  
  654. include codeseg.inc
  655.         .
  656.         .
  657.         .
  658.         lea     esi,filespec
  659.         mov     bx,0             ; start at top of list
  660.         xor     ecx,ecx          ; normal files only
  661. IFDEF   GRAPHMODE
  662.         lea     eax,$gpick
  663.         lea     edx,xy
  664. ELSE
  665.         lea     eax,$tpick
  666.         xor     edx,edx          ; upper left corner of screen
  667. ENDIF
  668.         call    pickfile
  669.         cmp     ax,0Dh           ; was Enter the last key pressed?
  670.         jne     abort            ;  nope - someone wants out
  671.  
  672.  
  673. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  674.  
  675. PICKSTRING:  pick a string from a list of ASCIIZ strings
  676. Source:      pickstr.asm ($strlist.asm)
  677.  
  678. Call with:   ESI pointing to list of ASCIIZ strings
  679.              BX = initial cursor position
  680.  
  681.              [text modes]
  682.              EAX = near pointer to ASM32's $TPICK module
  683.              DH = top screen row for list
  684.              DL = left screen column for list
  685.  
  686.              [graphics modes]
  687.              EAX = near poitner to ASM32's $GPICK module
  688.              EDX = near pointer to (x,y) screen coordinates
  689.                    for upper left corner of filename list
  690.  
  691.              PickString pops a window on the screen and displays the list
  692.              of strings.  One string may be selected with cursor keys
  693.              or with hotkeys.  When Esc, Enter or ^C is pressed, PickString
  694.              restores the screen and returns a string index number.
  695.              See also MenuOption.  Maximum number of choices: 255
  696.  
  697. Returns:     AX = last key pressed
  698.              EBX = string number selected (first string = 0)
  699. Uses:        EAX, EBX, flags
  700. Supports:    text mode
  701.  
  702. (Example on next page)
  703.  
  704. PICKSTRING Example:
  705.  
  706. public  myproc
  707. extrn   pickstring:near
  708. IFDEF   GRAPHMODE
  709. extrn   $gpick:near
  710. ELSE
  711. extrn   $tpick:near
  712. ENDIF
  713.  
  714. include dataseg.inc
  715.  
  716. string1 db 'January',0
  717.         db 'February',0
  718.         db 'March',0
  719.         db 'April',0
  720.         db 'May',0
  721.         db 'June',0
  722.         db 'July',0
  723.         db 'August',0
  724.         db 'September',0
  725.         db 'October',0
  726.         db 'November',0
  727.         db 'December',0
  728.         db 0              ; mark end of menu strings
  729.  
  730. @curseg ends
  731.  
  732. include codeseg.inc
  733.  
  734.         .
  735.         .
  736.         lea  esi,string1
  737.         mov  bx,1
  738. IFDEF   GRAPHMODE
  739.         lea     eax,$gpick
  740.         lea     edx,xy
  741. ELSE
  742.         lea     eax,$tpick
  743.         xor     edx,edx          ; upper left corner of screen
  744. ENDIF
  745.         call pickstring
  746.  
  747.  
  748. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  749.  
  750. PULLDOWN:    pull-down menu system
  751. Source:      pulldown.asm ($menu.asm, tprint.asm, tputchr.asm, strlen.asm,
  752.                            wclear.asm, wframe.asm, wsize.asm, wsave.asm,
  753.                            getkey.asm, pickstr.asm and others)
  754.  
  755. Call with:   [ESI] pointing to menu labels
  756.              BL = initial main menu choice, BH = initial submenu choice
  757.  
  758.              If PullDown is called with BH = 0FFh, only the main headings are
  759.              printed initally; the submenus are printed when ENTER is
  760.              pressed or a mouse button is pressed.
  761.  
  762.              If PullDown is called with BL <> 0FFh, it starts in the full
  763.              main headings plus submenus mode.  In this mode, a mouse button
  764.              click or the ENTER key will exit PullDown.  In either mode,
  765.              ESC, ^C or the user-defined quitkey (see MenuOption) causes
  766.              PullDown to return to the calling program.
  767.  
  768.              If there are too many main headings to fit across the top of the
  769.              screen, the headings are scrolled left or right as required to
  770.              show the selected heading.  Use Left, Right, Home and End keys
  771.              to change selected headings.
  772.  
  773.              If there are too many submenu choices under a heading to fit
  774.              on the screen, the selections are scrolled up or down as required
  775.              to show the selected item.  Use Up, Down, PgUp, PgDown keys
  776.              to change selection, or press highlighted letter of selection.
  777.              Maximum number of selections per heading: 255
  778.  
  779. Returns:     BL = main menu choice, BH = submenu choice
  780.              if CF = 1, ^C or Ctrl-Break was pressed
  781.              if CF = 0
  782.                  AX = 13 if ENTER was pressed
  783.                  AX = user-defined quitkey if pressed (see MenuOption)
  784.                  AX = 27 if ESC was pressed
  785.                  AH = 1-7, AL = 0 if mouse button pressed
  786. Uses:        AX, BX
  787. Supports:    text mode; all row/column configurations supported by ASM32
  788.              Text subroutines
  789. Example:
  790.  
  791. see next page
  792.  
  793.  
  794. ;    this sample menu has 4 main menu headings:
  795. ;                          Critters, Things, Food, Trees
  796. ;    submenu choices for each main heading follow each main heading
  797. ;    Note that each string is terminated with NUL, and that there's an
  798. ;    extra NUL between the end of the submenu choices and the next main
  799. ;    heading.
  800. ;    The entire set of menu choices is terminated with 2 NUL bytes
  801. ;
  802. ;    PULLDOWN will return to the calling program when either ESCAPE or
  803. ;    ENTER is pressed (AX = ASCII code of key pressed).  PULLDOWN returns
  804. ;    AX = 0 if insufficient memory is available to save the underlying
  805. ;    screen, or AX = 3 if breaktrap was enabled and Ctrl+Break was pressed.
  806. ;
  807. ;    On return, BH = the main heading and BL = the submenu choice in effect
  808. ;    when the key was pressed.  The first main heading is number 0, and
  809. ;    the first submenu choice for each main heading is also number 0.
  810.  
  811. include model.inc
  812.  
  813. extrn   pulldown:near
  814.  
  815. include dataseg.inc
  816. menu    db 'Critters',0
  817.         db 'Goats',0,'Chickens',0,'Turkeys',0,'Cows',0,'Snow dogs',0
  818.  
  819.         db 0                   ; separate Things from Critters
  820.         db 'Things',0
  821.         db 'Computers',0,'Tractors',0,'CPU chips',0,'Barbie dolls',0
  822.  
  823.         db 0                   ; separate Food from Things
  824.         db 'Food',0
  825.         db 'Hot dogs',0,'Wheat germ',0,'Lasagne',0,'Cheerios',0
  826.         db 'Potatoes',0,'chocolate chip cooKies',0
  827.  
  828.         db 0                   ; separate Trees from Food
  829.         db 'Trees',0
  830.         db 'giant Sequoia',0,'black Spruce',0,'Willow',0,'live Oak',0
  831.         db 'Acacia',0,'digger Pine',0
  832.  
  833.         db 2 dup(0)            ; end of menu choices
  834.  
  835. include codeseg.inc
  836.         .
  837.         .
  838.         .
  839.         lea   esi,menu          ; point to menu labels
  840.         xor   ebx,ebx           ; initial selection is "goats"
  841.         call  pulldown
  842.  
  843.  
  844. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  845.  
  846. PUTKEY:      put a keycode in the keyboard's type-ahead buffer
  847. Source:      putkey.asm (kbdtype.asm)
  848.  
  849. Call with:   AH = key scan code
  850.              AL = key ASCII code
  851. Returns:     CF = 1 if keyboard buffer is full
  852. Uses:        flags
  853. Supports:    standard and enhanced keyboards
  854.              standard keyboard support required by InBoard 386PC computers
  855. Example:
  856.  
  857. ; I want to put the keycode for the F10 key in the keyboard's buffer
  858.  
  859. extrn   putkey:proc
  860.  
  861. include codeseg.inc
  862.         .
  863.         .
  864.         .
  865.         mov     ax,4400h              ; AH = scan code, AL = ASCII code
  866.         call    putkey
  867.  
  868.  
  869.  
  870. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  871.  
  872. SINO:        Spanish language version of YesNo
  873.              waits for 'S' or 'N' key to be pressed
  874. Source:      sino.asm
  875.  
  876. Call with:   no parameters
  877.              Key pressed may be upper or lower case.  Upper case is
  878.              returned.  Uses BIOS functions
  879. Returns:     AX = 'S' or AX = 'N'
  880.              future version will also return ^C
  881. Uses:        AX
  882. Example:
  883.  
  884. extrn   sino:near
  885.  
  886. include codeseg.inc
  887.  
  888.         .
  889.         .
  890.         .
  891.         call  sino
  892.  
  893.  
  894. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  895.  
  896. TEDIT:       ASCIIZ string editor for text modes
  897.              See also GEdit for graphics modes, $edit for general information.
  898.              TEdit turns the cursor off (with CursorOFF) on exit.
  899. Source:      tedit.asm ($edit.asm, cursor.asm, a$clrw.asm, str2vbuf.asm,
  900.                         crtinfo.asm)
  901.  
  902. Call with:   ESI pointing to string buffer; may include a default string
  903.              ECX = byte size of buffer (excluding terminating NUL)
  904.              AH = color attribute
  905.              AL = option bits (see $edit)
  906.              DH = row (offset from top of screen)
  907.              DL = column (offset from left edge of screen)
  908.  
  909. Returns:     AX = last key pressed (see GetKey for key codes)
  910.              ECX = new string length
  911. Uses:        EAX, ECX, flags
  912. Supports:    text modes; all row/column configurations
  913. Example:
  914.  
  915. include dataseg.inc
  916.  
  917. string_buffer db 100 dup(0)
  918. len_buffer    equ 99               ; leave one byte for terminal NUL
  919. row           db 10
  920. column        db 40
  921. attr          db 12                ; color attribute
  922.  
  923. @curseg ends
  924.  
  925. include codeseg.inc
  926.         .
  927.         .
  928.         .
  929.         lea   esi,string_buffer    ; near address of string buffer
  930.         mov   ecx,len_buffer       ; byte length of buffer for the string
  931.         mov   dh,row
  932.         mov   dl,column
  933.         mov   ah,attr              ; color attribute
  934.         mov   al,2                 ; force lower case
  935.         call  tedit
  936.  
  937.  
  938.  
  939. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  940.  
  941. TMOUSELIMIT: limits mouse's range of motion on text mode screen
  942. Source:      tmlimit.asm
  943.  
  944. Call with:   DS:[BX] pointing to character coordinates of minimum and maximum
  945.              rows and columns.  Columns are the horizontal dimension and
  946.              rows are the vertical dimension.
  947. Returns:     nothing
  948. Uses:        nothing
  949. Example:
  950.  
  951. .data
  952.  
  953. x0    dw 3          ; first row
  954. y0    dw 1          ; first column
  955. x1    dw 20         ; last row
  956. y1    dw 50         ; last column
  957.  
  958. .code
  959. ; program fragment assumes DS:@DATA
  960.        .
  961.        .
  962.        .
  963.       lea    bx,x          ; DS:[BX] points to limits
  964.       call   tmouselimit
  965.  
  966. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  967.  
  968. TMOUSEPOS:   set mouse position on text-mode screen
  969. Source:      tmouspos.asm
  970.  
  971. Call with:   DH = row (vertical position)
  972.              DL = column (horizontal position)
  973. Returns:     nothing
  974. Uses:        flags
  975. Example:
  976.  
  977. ; I want to center the mouse cursor on a standard 80-column, 25-row screen
  978.  
  979. include asm.inc
  980.  
  981. extrn   tmousepos:proc
  982.  
  983. .code
  984.         .
  985.         .
  986.         .
  987.         mov    dh,12           ; close to vertical center
  988.                                ; coordinates are 0 through 24 vertially
  989.         mov    dl,39           ; coordinates are 0 through 79 horizontally
  990.         call   tmousepos
  991.  
  992.  
  993. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  994.  
  995. TMOUSESTATUS:determine mouse position on text screen & buttons pressed
  996. Source:      tmstatus.asm
  997.  
  998. Call with:   no parameters
  999.              assumes mouse is installed (see IsMouse in SYSTEM.DOC)
  1000. Returns:     DH = row (vertical position)
  1001.              DL = column (horizontal position)
  1002.              if ZF = 1, no buttons are pressed
  1003.              if ZF = 0, BX = button code
  1004.               BX bit 0 if set = left button is down
  1005.               BX bit 1 if set = right button is down
  1006.               BX bit 2 if set = center button is down
  1007. Uses:        EBX, DX, flags
  1008. Example:     call  tmousestatus
  1009.              jz    no_buttons     ; no buttons pressed if ZF = 1
  1010.  
  1011.  
  1012.  
  1013. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1014.  
  1015. TOLOWER:     converts keycode returned by getkey to lower case
  1016. Source:      tolower.asm
  1017.  
  1018. Call with:   AX = keycode
  1019. Returns:     AX = lower case keycode
  1020.              ToLower leaves the keycode alone if the keycode is not
  1021.              upper case A-Z.
  1022. Uses:        AX
  1023. Example:     call   getkey
  1024.              call   tolower
  1025.  
  1026.  
  1027. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1028.  
  1029. TOUPPER:     converts keycode returned by getkey to upper case
  1030. Source:      toupper.asm
  1031.  
  1032. Call with:   AX = keycode
  1033. Returns:     AX = upper case keycode
  1034.              ToUpper leaves the keycode alone if the keycode is not
  1035.              lower case a-z.
  1036. Uses:        AX
  1037. Example:     call   getkey
  1038.              call   toupper
  1039.  
  1040.  
  1041. ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
  1042.  
  1043. YESNO:       waits for 'Y' or 'N' key to be pressed
  1044. Source:      yesno.asm
  1045.  
  1046. Call with:   no parameters
  1047.              Key pressed may be upper or lower case.  Upper case is
  1048.              returned.  Uses BIOS functions
  1049. Returns:     AX = 'Y' or AX = 'N'
  1050.              future version will also return ^C
  1051. Uses:        AX
  1052. Example:
  1053.  
  1054. extrn   yesno:near
  1055.  
  1056. include codeseg.inc
  1057.  
  1058.         .
  1059.         .
  1060.         .
  1061.         call  yesno
  1062.  
  1063.  
  1064.